Zum Hauptinhalt springen

Rest API Usage

OpenTalk bietet eine REST API, mit der sich z.B. die Raumerstellung in andere Anwendungen, Portale, automatisierte Prozesse o.ä. integrieren lässt.

Die API ist unter https://docs.opentalk.eu/developer/controller/rest beschrieben.

Dieser Artikel gibt eine kurze Übersicht zur Nutzung anhand eines Bash-Scripts. Die Abfolge der Befehle lässt sich dann in andere Sprachen übertragen.

Beachten Sie das in Keycloak unter Clients/Authentication Flow die Option "Direct access grants" aktiviert sein muss. Wenn Sie wie im Beispiel OtFrontend als client ID benutzen gehen Sie in Keycloak auf Clients (linke Leiste) und wählen OtFrontend aus der Liste. Unter Capability config/Authentication flow finden Sie Direct access grants. Schalten Sie diese Option an.

Login​

Sie müssen sich zuerst über OAuth anmelden (keycloak) um das API anzusteuern.

Folgende Daten werden dazu benötigt, ersetzen Sie die Beispielwerte mit ihren Daten:

OT_USER=m.mustermann@example.com
OT_PASSWORD=secret

OT_MAIN_URL=meet.opentalk.eu
OT_KEYCLOAK_URL=accounts.${OT_MAIN_URL}
OT_CONTROLLER_URL=controller.${OT_MAIN_URL}
OT_PROTO=https://

# die beiden folgenden Werte finden in keycloak oder wenn Sie sich einloggen im Browser, z.B.:
# https://accounts.meet.opentalk.eu/auth/realms/admdemo/login-actions/
# authenticate?session_code=<session>&client_id=openid_admdemo_test_public&..
OT_CLIENT_ID=OtFrontend
OT_REALM_NAME=opentalk

Token anfordern​

Zuerst brauchen Sie einen Token von Keycloak:

OT_TOKEN=$(curl -s -d 'client_id='${OT_CLIENT_ID}'' \
					-d 'username='${OT_USER}'' \
					-d 'password='${OT_PASSWORD}'' \
					-d 'scope=openid' \
					-d 'grant_type=password' \
					'https://'${OT_KEYCLOAK_URL}'/auth/realms/'${OT_REALM_NAME}'/protocol/openid-connect/token')

Token extrahieren​

Sie können jq benutzen um den Token zu extrahieren:

OT_TOKEN="$(echo "$OT_TOKEN" | jq -r .access_token)"

Session anfordern​

Mit dem Token können Sie die Session anfordern:

OT_SESSION=$(curl -s -X POST 'https://'${OT_CONTROLLER_URL}'/v1/auth/login' \
				-H 'Content-Type: application/json' \
				-d '{ "id_token": "'${OT_TOKEN}'" }')

Die Session wird nicht weiter gebraucht, muss aber angefordert werden. Danach kann die Rest API angesprochen werden.

Beispiele​

Raumliste holen​

curl -s "https://${OT_CONTROLLER_URL}/v1/rooms" \
	-H 'Content-Type: application/json' \
	-H "authorization: Bearer $OT_TOKEN"

Rauminformation​

Die $ROOM_ID kommt aus der Raumliste:

curl -s "https://${OT_CONTROLLER_URL}/v1/rooms/$ROOM_ID" \
	-H 'Content-Type: application/json' \
	-H "authorization: Bearer $OT_TOKEN"

Liste aller Events:​

curl -s "https://${OT_CONTROLLER_URL}/v1/events?per_page=60&adhoc=false" \
	-H 'Content-Type: application/json' \
	-H "authorization: Bearer $OT_TOKEN"

Hier wurde der per_page parameter hinzugefügt, ohne werden maximal 30 Einträge angezeigt. was auch für andere Aufrufe gilt. Bitte referenzieren Sie die API Dokumentation für alle Parameter wenn Sie die Ausgabe einschränken wollen, z.B. können Sie mit time_min und time_max den Zeitraum festlegen aus dem die Events angezeigt werden.

Bash Script​

Ein erweitertes script mit mehr Beispielen:

#!/bin/bash

OT_USER=testuser@example.com
OT_PASSWORD=secret

OT_MAIN_URL=meet.opentalk.eu
OT_KEYCLOAK_URL=accounts.${OT_MAIN_URL}
OT_CONTROLLER_URL=controller.${OT_MAIN_URL}
OT_PROTO=https://

# if the next two values are not known you can read them from the URL when
# logging in:
# https://accounts.meet.opentalk.eu/auth/realms/admdemo/login-actions/
# authenticate?session_code=<session>&client_id=openid_admdemo_test_public&..
OT_CLIENT_ID=OtFrontend
OT_REALM_NAME=opentalk

DEFAULT_EXPIRATION_HOURS=24
GET_MAX_EVENTS=30

# you probably want to store the credentials and other variables
# in a configuration file
OT_CONFIG=~/.opentalk_api.rc
if [ -r "$OT_CONFIG" ]; then
    . "$OT_CONFIG"
fi

# nothing to change below
usage () {
    SCRIPT=$(basename $0)
echo "$SCRIPT -c              create event (--create)
$SCRIPT -l              list events (--list-events)
$SCRIPT -r              list rooms (--rooms)
$SCRIPT -i <room id>    show information for room (--info)
"
    exit 0
}

ot_login () {
    OT_TOKEN=$(curl -s -d 'client_id='${OT_CLIENT_ID}'' \
                    -d 'username='${OT_USER}'' \
                    -d 'password='${OT_PASSWORD}'' \
                    -d 'scope=openid' \
                    -d 'grant_type=password' \
                    'https://'${OT_KEYCLOAK_URL}'/auth/realms/'${OT_REALM_NAME}'/protocol/openid-connect/token')

        if [ "$(echo "$OT_TOKEN" | grep \"access_token\":)" = "" ]; then
            echo "- something went wrong getting token:"
            echo "$OT_TOKEN"
            exit 1
        else
            OT_TOKEN="$(echo "$OT_TOKEN" | jq -r .access_token)"
        fi

        SESSION=$(curl -s -X POST 'https://'${OT_CONTROLLER_URL}'/v1/auth/login' \
                -H 'Content-Type: application/json' \
                -d '{ "id_token": "'${OT_TOKEN}'" }')
}

ot_create_room () {
    E_ROOM_ID=$(curl -s -X POST 'https://'${OT_CONTROLLER_URL}'/v1/rooms' \
            -H "Authorization: Bearer ${OT_TOKEN}" -H 'Content-Type: application/json' \
            -d '{"password": null, "enable_sip": false, "waiting_room": false}' )

    if [ "$(echo "$E_ROOM_ID" | grep \"id\":)" = "" ]; then
        echo "- something went wrong:"
        echo "$E_ROOM_ID"
        exit 1
    fi

    E_ROOM_ID="$(echo "$E_ROOM_ID" | jq -r .id)"
    ot_get_invite
    echo "Room: ${OT_PROTO}${OT_MAIN_URL}/room/$E_ROOM_ID Guest: $INVITE_LINK"
}

ot_get_invite () {
    EXPIRATION_DATE=$(date --date="-${DEFAULT_EXPIRATION_HOURS} hours ago" +"%Y-%m-%dT%H:%M:%SZ")
    INVITE_CODE=$(curl -s -X POST "https://${OT_CONTROLLER_URL}/v1/rooms/${E_ROOM_ID}/invites" \
            -H "Authorization: Bearer ${OT_TOKEN}" -H 'Content-Type: application/json' \
            -d '{"expiration": "'${EXPIRATION_DATE}'"}' | jq -r '.invite_code' \
            )
    INVITE_LINK="${OT_PROTO}${OT_MAIN_URL}/invite/${INVITE_CODE}"
}

ot_get_rooms () {
    ROOM_LIST=$(curl -s "https://${OT_CONTROLLER_URL}/v1/rooms?per_page=${GET_MAX_EVENTS}" \
    -H 'Content-Type: application/json' \
    -H "authorization: Bearer $OT_TOKEN")

    ROOM_COUNT="$(echo "$ROOM_LIST" | jq '. | length')"
    ROOM_COUNT=$((ROOM_COUNT - 1))

    echo $ROOM_LIST > /tmp/rl

    echo "number,room id"

    for ROOM in $(seq 0 $ROOM_COUNT); do
        E_ROOM_ID=$(echo $ROOM_LIST | jq -r '.['$ROOM'] | .id')
        echo "$ROOM $E_ROOM_ID"
    done
}

ot_get_room_info () {
    ROOM_ID=$1
    if [ "$ROOM_ID" = "" ]; then
        echo "please use the room id as parameter"
        usage | grep -- --info
    fi
    ROOM_INFO=$(curl -s "https://${OT_CONTROLLER_URL}/v1/rooms/$ROOM_ID" \
    -H 'Content-Type: application/json' \
    -H "authorization: Bearer $OT_TOKEN")

    echo $ROOM_INFO
}

ot_get_events () {
  EVENT_LIST=$(curl -s "https://${OT_CONTROLLER_URL}/v1/events?per_page=${GET_MAX_EVENTS}&adhoc=false" \
    -H 'Content-Type: application/json' \
    -H "authorization: Bearer $OT_TOKEN")

    EVENT_COUNT="$(echo "$EVENT_LIST" | jq '. | length')"
    EVENT_COUNT=$((EVENT_COUNT - 1))

    echo "$EVENT_LIST" > /tmp/el

    echo "number,title,room_link,start,end,sip,password,guest_link"

    for EVENT in $(seq 0 $EVENT_COUNT); do
        E_ROOM_ID=$(echo $EVENT_LIST | jq -r '.['$EVENT'] | .room.id')
        E_ROOM_LINK="${OT_PROTO}${OT_MAIN_URL}/room/$E_ROOM_ID"
        E_ROOM_TITLE=$(echo $EVENT_LIST | jq '.['$EVENT'] | .title')
        E_START=$(echo $EVENT_LIST | jq '.['$EVENT'] | .starts_at.datetime')
        E_END=$(echo $EVENT_LIST | jq '.['$EVENT'] | .ends_at.datetime')
        E_SIP=$(echo $EVENT_LIST | jq '.['$EVENT'] | "\(.room.sip_tel),,\(.room.sip_id),,\(.room.sip_password)"')
        E_PASSWORD=$(echo $EVENT_LIST | jq '.['$EVENT'] | .room.password')
        ot_get_invite
        echo "$EVENT $E_ROOM_TITLE,$E_ROOM_LINK,$E_START,$E_END,$E_SIP,$E_PASSWORD,$INVITE_LINK"
    done
}

case "$1" in
    -l|--list-events)
            ot_login
            ot_get_events ;;
    -c|--create-room)
            ot_login
            ot_create_room ;;
    -r|--rooms )
            ot_login
            ot_get_rooms ;;
    -i|--info )
            ot_login
            ot_get_room_info $2 ;;
    *) usage ;;
esac